home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 27 / CU Amiga Magazine's Super CD-ROM 27 (1998)(EMAP Images)(GB)[!][issue 1998-10].iso / CUCD / Sound / SPlayer / Socks5 / doc / rfc1961.txt < prev    next >
Text File  |  1996-06-28  |  16KB  |  416 lines
  1. rfc1961
  2.  
  3. Press here to go to the top of the rfc 'tree'.
  4.  
  5. Network Working Group                                         P. McMahon
  6. Request for Comments: 1961                                           ICL
  7. Category: Standards Track                                      June 1996
  8.  
  9.            GSS-API Authentication Method for SOCKS Version 5
  10.  
  11. Status of this Memo
  12.  
  13.    This document specifies an Internet standards track protocol for the
  14.    Internet community, and requests discussion and suggestions for
  15.    improvements.  Please refer to the current edition of the "Internet
  16.    Official Protocol Standards" (STD 1) for the standardization state
  17.    and status of this protocol.  Distribution of this memo is unlimited.
  18.  
  19. Table of Contents
  20.  
  21.          1. Purpose ............................................ 1
  22.          2. Introduction ....................................... 1
  23.          3. GSS-API Security Context Establishment ............. 2
  24.          4. GSS-API Protection-level Options ................... 5
  25.          5. GSS-API Per-message Protection ..................... 7
  26.          6. GSS-API Security Context Termination ............... 8
  27.          7. References ......................................... 8
  28.          8. Acknowledgments .................................... 8
  29.          9. Security Considerations ............................ 8
  30.          10. Author's Address .................................. 9
  31.  
  32. 1. Purpose
  33.  
  34.    The protocol specification for SOCKS Version 5 specifies a
  35.    generalized framework for the use of arbitrary authentication
  36.    protocols in the initial SOCKS connection setup.  This document
  37.    provides the specification for the SOCKS V5 GSS-API authentication
  38.    protocol, and defines a GSS-API-based encapsulation for provision of
  39.    integrity, authentication and optional confidentiality.
  40.  
  41. 2. Introduction
  42.  
  43.    GSS-API provides an abstract interface which provides security
  44.    services for use in distributed applications, but isolates callers
  45.    from specific security mechanisms and implementations.
  46.  
  47.    GSS-API peers achieve interoperability by establishing a common
  48.    security mechanism for security context establishment - either
  49.    through administrative action, or through negotiation.  GSS-API is
  50.    specified in [RFC 1508], and [RFC 1509].  This specification is
  51.    intended for use with implementations of GSS-API, and the emerging
  52.  
  53. McMahon                     Standards Track                     [Page 1]
  54.  
  55. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  56.  
  57.    GSS-API V2 specification.
  58.  
  59.    The approach for use of GSS-API in SOCKS V5 is to authenticate the
  60.    client and server by successfully establishing a GSS-API security
  61.    context - such that the GSS-API encapsulates any negotiation protocol
  62.    for mechanism selection, and the agreement of security service
  63.    options.
  64.  
  65.    The GSS-API enables the context initiator to know what security
  66.    services the target supports for the chosen mechanism.  The required
  67.    level of protection is then agreed by negotiation.
  68.  
  69.    The GSS-API per-message protection calls are subsequently used to
  70.    encapsulate any further TCP and UDP traffic between client and
  71.    server.
  72.  
  73. 3. GSS-API Security Context Establishment
  74.  
  75. 3.1 Preparation
  76.  
  77.    Prior to use of GSS-API primitives, the client and server should be
  78.    locally authenticated, and have established default GSS-API
  79.    credentials.
  80.  
  81.    The client should call gss_import_name to obtain an internal
  82.    representation of the server name.  For maximal portability the
  83.    default name_type GSS_C_NULL_OID should be used to specify the
  84.    default name space, and the input name_string should treated by the
  85.    client's code as an opaque name-space specific input.
  86.  
  87.    For example, when using Kerberos V5 naming, the imported name may be
  88.    of the form "SERVICE:socks@socks_server_hostname" where
  89.    "socks_server_hostname" is the fully qualified host name of the
  90.    server with all letters in lower case. Other mechanisms may, however,
  91.    have different name forms, so the client should not make assumptions
  92.    about the name syntax.
  93.  
  94. 3.2 Client Context Establishment
  95.  
  96.    The client should then call gss_init_sec_context, typically passing:
  97.  
  98.          GSS_C_NO_CREDENTIAL into cred_handle to specify the default
  99.          credential (for initiator usage),
  100.  
  101.          GSS_C_NULL_OID into mech_type to specify the default
  102.          mechanism,
  103.  
  104. McMahon                     Standards Track                     [Page 2]
  105.  
  106. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  107.  
  108.          GSS_C_NO_CONTEXT into context_handle to specify a NULL
  109.          context (initially), and,
  110.  
  111.          the previously imported server name into target_name.
  112.  
  113.    The client must also specify its requirements for replay protection,
  114.    delegation, and sequence protection via the gss_init_sec_context
  115.    req_flags parameter.  It is required by this specification that the
  116.    client always requests these service options (i.e. passes
  117.    GSS_C_MUTUAL_FLAG | GSS_C_REPLAY_FLAG | GSS_C_DELEG_FLAG |
  118.    GSS_C_SEQUENCE_FLAG into req_flags).
  119.  
  120.    However, GSS_C_SEQUENCE_FLAG should only be passed in for TCP-based
  121.    clients, not for UDP-based clients.
  122.  
  123. 3.3 Client Context Establishment Major Status codes
  124.  
  125.    The gss_init_sec_context returned status code can take two different
  126.    success values:
  127.  
  128.     - If gss_init_sec_context returns GSS_S_CONTINUE_NEEDED, then the
  129.       client should expect the server to issue a token in the
  130.       subsequent subnegotiation response.  The client must pass the
  131.       token to another call to gss_init_sec_context, and repeat this
  132.       procedure until "continue" operations are complete.
  133.  
  134.     - If gss_init_sec_context returns GSS_S_COMPLETE, then the client
  135.       should respond to the server with any resulting output_token.
  136.  
  137.       If there is no output_token, the client should proceed to send
  138.       the protected request details, including any required message
  139.       protection subnegotiation as specified in sections 4 and 5
  140.       below.
  141.  
  142. 3.4 Client initial token
  143.  
  144.    The client's GSS-API implementation then typically responds with the
  145.    resulting output_token which the client sends in a message to the
  146.    server.
  147.  
  148.     +------+------+------+.......................+
  149.     + ver  | mtyp | len  |       token           |
  150.     +------+------+------+.......................+
  151.     + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets |
  152.     +------+------+------+.......................+
  153.  
  154. McMahon                     Standards Track                     [Page 3]
  155.  
  156. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  157.  
  158.     Where:
  159.  
  160.     - "ver" is the protocol version number, here 1 to represent the
  161.       first version of the SOCKS/GSS-API protocol
  162.  
  163.     - "mtyp" is the message type, here 1 to represent an
  164.       authentication message
  165.  
  166.     - "len" is the length of the "token" field in octets
  167.  
  168.     - "token" is the opaque authentication token emitted by GSS-API
  169.  
  170. 3.5 Client GSS-API Initialisation Failure
  171.  
  172.    If, however, the client's GSS-API implementation failed during
  173.    gss_init_sec_context, the client must close its connection to the
  174.    server.
  175.  
  176. 3.6 Server Context Establishment
  177.  
  178.    For the case where a client successfully sends a token emitted by
  179.    gss_init_sec_context() to the server, the server must pass the
  180.    client-supplied token to gss_accept_sec_context as input_token.
  181.  
  182.    When calling gss_accept_sec_context() for the first time, the
  183.    context_handle argument is initially set to GSS_C_NO_CONTEXT.
  184.  
  185.    For portability, verifier_cred_handle is set to GSS_C_NO_CREDENTIAL
  186.    to specify default credentials (for acceptor usage).
  187.  
  188.    If gss_accept_sec_context returns GSS_CONTINUE_NEEDED, the server
  189.    should return the generated output_token to the client, and
  190.    subsequently pass the resulting client supplied token to another call
  191.    to gss_accept_sec_context.
  192.  
  193.    If gss_accept_sec_context returns GSS_S_COMPLETE, then, if an
  194.    output_token is returned, the server should return it to the client.
  195.  
  196.    If no token is returned, a zero length token should be sent by the
  197.    server to signal to the client that it is ready to receive the
  198.    client's request.
  199.  
  200. McMahon                     Standards Track                     [Page 4]
  201.  
  202. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  203.  
  204. 3.7 Server Reply
  205.  
  206.    In all continue/confirmation cases, the server uses the same message
  207.    type as for the client -> server interaction.
  208.  
  209.     +------+------+------+.......................+
  210.     + ver  | mtyp | len  |       token           |
  211.     +------+------+------+.......................+
  212.     + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets |
  213.     +------+------+------+.......................+
  214.  
  215. 3.8 Security Context Failure
  216.  
  217.    If the server refuses the client's connection for any reason (GSS-API
  218.    authentication failure or otherwise), it will return:
  219.  
  220.     +------+------+
  221.     + ver  | mtyp |
  222.     +------+------+
  223.     + 0x01 | 0xff |
  224.     +------+------+
  225.  
  226.     Where:
  227.  
  228.     - "ver" is the protocol version number, here 1 to represent the
  229.       first version of the SOCKS/GSS-API protocol
  230.  
  231.     - "mtyp" is the message type, here 0xff to represent an abort
  232.       message
  233.  
  234. 4. GSS-API Protection-level Options
  235.  
  236. 4.1 Message protection
  237.  
  238.    Establishment of a GSS-API security context enables comunicating
  239.    peers to determine which per-message protection services are
  240.    available to them through the gss_init_sec_context() and
  241.    gss_accept_sec_context() ret_flags GSS_C_INTEG_FLAG and
  242.    GSS_C_CONF_FLAG which respectively indicate message integrity and
  243.    confidentiality services.
  244.  
  245.    It is necessary to ensure that the message protection applied to the
  246.    traffic is appropriate to the sensitivity of the data, and the
  247.    severity of the threats.
  248.  
  249. McMahon                     Standards Track                     [Page 5]
  250.  
  251. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  252.  
  253. 4.2 Message Protection Subnegotiation
  254.  
  255.    For TCP and UDP clients and servers, different levels of protection
  256.    are possible in the SOCKS V5 protocol, so an additional
  257.    subnegotiation stage is needed to agree the message protection level.
  258.    After successful completion of this subnegotiation, TCP and UDP
  259.    clients and servers use GSS-API encapsulation as defined in section
  260.    5.1.
  261.  
  262.    After successful establishment of a GSS-API security context, the
  263.    client's GSS-API implementation sends its required security context
  264.    protection level to the server.  The server then returns the security
  265.    context protection level which it agrees to - which may or may not
  266.    take the the client's request into account.
  267.  
  268.    The security context protection level sent by client and server must
  269.    be one of the following values:
  270.  
  271.          1 required per-message integrity
  272.          2 required per-message integrity and confidentiality
  273.          3 selective per-message integrity or confidentiality based on
  274.            local client and server configurations
  275.  
  276.    It is anticipated that most implementations will agree on level 1 or
  277.    2 due to the practical difficulties in applying selective controls to
  278.    messages passed through a socks library.
  279.  
  280. 4.3 Message Protection Subnegotiation Message Format
  281.  
  282.    The security context protection level is sent from client to server
  283.    and vice versa using the following protected message format:
  284.  
  285.     +------+------+------+.......................+
  286.     + ver  | mtyp | len  |   token               |
  287.     +------+------+------+.......................+
  288.     + 0x01 | 0x02 | 0x02 | up to 2^16 - 1 octets |
  289.     +------+------+------+.......................+
  290.  
  291.     Where:
  292.  
  293.     - "ver" is the protocol version number, here 1 to represent the
  294.       first version of the SOCKS/GSS-API protocol
  295.  
  296.     - "mtyp" is the message type, here 2 to represent a protection
  297.       -level negotiation message
  298.  
  299.     - "len" is the length of the "token" field in octets
  300.  
  301. McMahon                     Standards Track                     [Page 6]
  302.  
  303. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  304.  
  305.     - "token" is the GSS-API encapsulated protection level
  306.  
  307. 4.4 Message Protection Subnegotiation Message Generation
  308.  
  309.    The token is produced by encapsulating an octet containing the
  310.    required protection level using gss_seal()/gss_wrap() with conf_req
  311.    set to FALSE.  The token is verified using gss_unseal()/
  312.    gss_unwrap().
  313.  
  314.    If the server's choice of protection level is unacceptable to the
  315.    client, then the client must close its connection to the server
  316.  
  317. 5. GSS-API Per-message Protection
  318.  
  319.    For TCP and UDP clients and servers, the GSS-API functions for
  320.    encapsulation and de-encapsulation shall be used by implementations -
  321.    i.e. gss_seal()/gss_wrap(), and gss_unseal()/ gss_unwrap().
  322.  
  323.    The default value of quality of protection shall be specified, and
  324.    the use of conf_req_flag shall be as determined by the previous
  325.    subnegotiation step.  If protection level 1 is agreed then
  326.    conf_req_flag MUST always be FALSE; if protection level 2 is agreed
  327.    then conf_req_flag MUST always be TRUE; and if protection level 3 is
  328.    agreed then conf_req is determined on a per-message basis by client
  329.    and server using local configuration.
  330.  
  331.    All encapsulated messages are prefixed by the following framing:
  332.  
  333.     +------+------+------+.......................+
  334.     + ver  | mtyp | len  |       token           |
  335.     +------+------+------+.......................+
  336.     + 0x01 | 0x03 | 0x02 | up to 2^16 - 1 octets |
  337.     +------+------+------+.......................+
  338.  
  339.     Where:
  340.  
  341.     - "ver" is the protocol version number, here 1 to represent the
  342.       first version of the SOCKS/GSS-API protocol
  343.  
  344.     - "mtyp" is the message type, here 3 to represent encapulated user
  345.       data
  346.  
  347.     - "len" is the length of the "token" field in octets
  348.  
  349.     - "token" is the user data encapsulated by GSS-API
  350.  
  351. McMahon                     Standards Track                     [Page 7]
  352.  
  353. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  354.  
  355. 6. GSS-API Security Context Termination
  356.  
  357.    The GSS-API context termination message (emitted by
  358.    gss_delete_sec_context) is not used by this protocol.
  359.  
  360.    When the connection is closed, each peer invokes
  361.    gss_delete_sec_context() passing GSS_C_NO_BUFFER into the
  362.    output_token argument.
  363.  
  364. 7. References
  365.  
  366.     [RFC 1508] Linn, J., "Generic Security Service API",
  367.                September 1993.
  368.  
  369.     [RFC 1509] Wray, J., "Generic Security Service API : C-bindings",
  370.                September 1993.
  371.  
  372.     [SOCKS V5] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D.,
  373.                and L. Jones, "SOCKS Protocol V5", RFC 1928, April
  374.                1996.
  375.  
  376. 8. Acknowledgment
  377.  
  378.    This document builds from a previous memo produced by Marcus Leech
  379.    (BNR) - whose comments are gratefully acknowleged.  It also reflects
  380.    input from the AFT WG, and comments arising from implementation
  381.    experience by Xavier Gosselin (IUT Lyons).
  382.  
  383. 9. Security Considerations
  384.  
  385.    The security services provided through the GSS-API are entirely
  386.    dependent on the effectiveness of the underlying security mechanisms,
  387.    and the correctness of the implementation of the underlying
  388.    algorithms and protocols.
  389.  
  390.    The user of a GSS-API service must ensure that the quality of
  391.    protection provided by the mechanism implementation is consistent
  392.    with their security policy.
  393.  
  394.    In addition, where negotiation is supported under the GSS-API,
  395.    constraints on acceptable mechanisms may be imposed to ensure
  396.    suitability for application to authenticated firewall traversal.
  397.  
  398. McMahon                     Standards Track                     [Page 8]
  399.  
  400. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  401.  
  402. 10. Author's Address
  403.  
  404.    P. V. McMahon
  405.    ICL Enterprises
  406.    Kings House
  407.    33 Kings Road
  408.    Reading, RG1 3PX
  409.    UK
  410.  
  411.    EMail: p.v.mcmahon@rea0803.wins.icl.co.uk
  412.    Phone: +44 1734 634882
  413.    Fax:   +44 1734 855106
  414.  
  415. McMahon                     Standards Track                     [Page 9]
  416.